

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>pyamp.documentation.rstGeneration &mdash; pyamp v1.2 documentation</title>
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.2',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <link rel="top" title="pyamp v1.2 documentation" href="../../../index.html" />
    <link rel="up" title="Module code" href="../../index.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li><a href="../../../index.html">pyamp v1.2 documentation</a> &raquo;</li>
          <li><a href="../../index.html" accesskey="U">Module code</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <h1>Source code for pyamp.documentation.rstGeneration</h1><div class="highlight"><pre>
<span class="c"># Copyright 2012 Brett Ponsler</span>
<span class="c"># This file is part of pyamp.</span>
<span class="c">#</span>
<span class="c"># pyamp is free software: you can redistribute it and/or modify</span>
<span class="c"># it under the terms of the GNU General Public License as published by</span>
<span class="c"># the Free Software Foundation, either version 3 of the License, or</span>
<span class="c"># (at your option) any later version.</span>
<span class="c">#</span>
<span class="c"># pyamp is distributed in the hope that it will be useful,</span>
<span class="c"># but WITHOUT ANY WARRANTY; without even the implied warranty of</span>
<span class="c"># MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the</span>
<span class="c"># GNU General Public License for more details.</span>
<span class="c">#</span>
<span class="c"># You should have received a copy of the GNU General Public License</span>
<span class="c"># along with pyamp.  If not, see &lt;http://www.gnu.org/licenses/&gt;.</span>
<span class="sd">&#39;&#39;&#39;The rstGeneration module contains classes and functions which provide</span>
<span class="sd">the ability to generate a single reStructured text formatted file for</span>
<span class="sd">each of the modules contained within a main Python project.</span>

<span class="sd">&#39;&#39;&#39;</span>
<span class="kn">from</span> <span class="nn">os</span> <span class="kn">import</span> <span class="n">curdir</span>
<span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">date</span>
<span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">OptionParser</span>
<span class="kn">from</span> <span class="nn">os.path</span> <span class="kn">import</span> <span class="n">abspath</span><span class="p">,</span> <span class="n">basename</span><span class="p">,</span> <span class="n">exists</span><span class="p">,</span> <span class="n">join</span><span class="p">,</span> <span class="n">split</span><span class="p">,</span> <span class="n">splitext</span>

<span class="kn">from</span> <span class="nn">pyamp.logging</span> <span class="kn">import</span> <span class="n">Loggable</span>
<span class="kn">from</span> <span class="nn">pyamp.util</span> <span class="kn">import</span> <span class="n">getPythonContents</span><span class="p">,</span> <span class="n">getClasses</span>


<div class="viewcode-block" id="RstOptions"><a class="viewcode-back" href="../../../_generated/pyamp_documentation_rstGeneration.html#pyamp.documentation.rstGeneration.RstOptions">[docs]</a><span class="k">class</span> <span class="nc">RstOptions</span><span class="p">:</span>
    <span class="sd">&#39;&#39;&#39;The RstOptions class encapsulates all the options that can be passed</span>
<span class="sd">    to the RST generation class to configure the generated output.</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">inheritance</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">overwrite</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">extension</span><span class="o">=</span><span class="s">&#39;.rst&#39;</span><span class="p">,</span>
                 <span class="n">ignoredModules</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">modifiedDirectory</span><span class="o">=</span><span class="s">&quot;_modified&quot;</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;</span>
<span class="sd">        * inheritance -- True to include inheritance diagrams for each class</span>
<span class="sd">        * overwrite -- True to overwrite existing files</span>
<span class="sd">        * extension -- The extension to use for generated files</span>
<span class="sd">        * ingoreModules -- The list of modules to ignore (i.e., no RST files</span>
<span class="sd">                           will be created for these modules)</span>
<span class="sd">        * modifiedDirectory -- The modified directory</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">inheritance</span> <span class="o">=</span> <span class="n">inheritance</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">overwrite</span> <span class="o">=</span> <span class="n">overwrite</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">extension</span> <span class="o">=</span> <span class="n">extension</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">ignoredModules</span> <span class="o">=</span> <span class="p">[]</span> <span class="k">if</span> <span class="n">ignoredModules</span> <span class="ow">is</span> <span class="bp">None</span> <span class="k">else</span> <span class="n">ignoredModules</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">modifiedDirectory</span> <span class="o">=</span> <span class="n">modifiedDirectory</span>

</div>
<div class="viewcode-block" id="RstBase"><a class="viewcode-back" href="../../../_generated/pyamp_documentation_rstGeneration.html#pyamp.documentation.rstGeneration.RstBase">[docs]</a><span class="k">class</span> <span class="nc">RstBase</span><span class="p">(</span><span class="n">Loggable</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;The RstBase class provides the base functionality used to create</span>
<span class="sd">    RstFiles based off of Python modules. It takes a module name and</span>
<span class="sd">    provides the ability to write the output in reStructured text format.</span>

<span class="sd">    &#39;&#39;&#39;</span>

    <span class="n">contentFunctions</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="sd">&#39;&#39;&#39;The contentFunctions property should be set to a list of class</span>
<span class="sd">    function names. These functions will be called, in order, to return a list</span>
<span class="sd">    of lines to add to the final generated file.</span>

<span class="sd">    Each content function takes an :class:`RstOptions` object as its only</span>
<span class="sd">    parameter, and should return a list of strings.</span>

<span class="sd">    &#39;&#39;&#39;</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">logData</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;</span>
<span class="sd">        * moduleName -- The name of the module which contains this module</span>
<span class="sd">        * logData -- The LogData object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">Loggable</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">logData</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span> <span class="o">=</span> <span class="n">moduleName</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_currentModuleName</span> <span class="o">=</span> <span class="s">&#39;.&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">moduleName</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&#39;.&#39;</span><span class="p">)[</span><span class="mi">0</span><span class="p">:</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_projectName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&#39;.&#39;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_baseName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&#39;.&#39;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>

<div class="viewcode-block" id="RstBase.write"><a class="viewcode-back" href="../../../_generated/pyamp_documentation_rstGeneration.html#pyamp.documentation.rstGeneration.RstBase.write">[docs]</a>    <span class="k">def</span> <span class="nf">write</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">directory</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Generate the reStructured text formatted file for this</span>
<span class="sd">        Python module.</span>

<span class="sd">        * directory -- The output directory in which to write the file</span>
<span class="sd">        * options -- The RstOptions to use when generating the file</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="n">directory</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_getFilename</span><span class="p">(</span><span class="n">options</span><span class="p">))</span>

        <span class="c"># Only create the RST file if: the file does not exist, or we are</span>
        <span class="c"># allowed to overwrite existing files, and this module is not expected</span>
        <span class="c"># to be ignored</span>
        <span class="k">if</span> <span class="p">(</span><span class="ow">not</span> <span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="ow">or</span> <span class="n">options</span><span class="o">.</span><span class="n">overwrite</span><span class="p">)</span> <span class="ow">and</span> \
                <span class="bp">self</span><span class="o">.</span><span class="n">_baseName</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">options</span><span class="o">.</span><span class="n">ignoredModules</span><span class="p">:</span>
            <span class="n">content</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_toRst</span><span class="p">(</span><span class="n">options</span><span class="p">)</span>

            <span class="k">if</span> <span class="n">exists</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s">&quot;Overwriting existing file [</span><span class="si">%s</span><span class="s">]&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_baseName</span><span class="p">)</span>

            <span class="c"># Write the file contents</span>
            <span class="n">fd</span> <span class="o">=</span> <span class="nb">file</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;w&#39;</span><span class="p">)</span>
            <span class="n">fd</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">content</span><span class="p">)</span>
            <span class="n">fd</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">filename</span> <span class="o">=</span> <span class="bp">None</span>

        <span class="k">return</span> <span class="n">filename</span>
</div>
    <span class="k">def</span> <span class="nf">_getFilename</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the name of the RST file to write.</span>

<span class="sd">        .. note:: This function **must** be overridden by subclasses.</span>

<span class="sd">        * _options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="c"># @todo: use an error class</span>
        <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">&quot;This function must be implemented by subclasses!&quot;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_toRst</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Convert the Python module to a reStructured text file.</span>

<span class="sd">        .. warning:: This function will raise an :class:`AttributError` in the</span>
<span class="sd">           event that the class does not contain one of the function names</span>
<span class="sd">           listed in the :attr:`contentFunctions` property.</span>

<span class="sd">        * options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">lines</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="c"># Create lines for all the different parts of content needed to</span>
        <span class="c"># create this RST file</span>
        <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">contentFunctions</span><span class="p">:</span>
            <span class="c"># Attempt to locate the function</span>
            <span class="c"># Note: This will throw an AttributeError if the function name</span>
            <span class="c"># could not be found</span>
            <span class="n">function</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>

            <span class="n">lines</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">function</span><span class="p">(</span><span class="n">options</span><span class="p">))</span>

            <span class="c"># Add an empty line to all but the last function</span>
            <span class="k">if</span> <span class="n">function</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">contentFunctions</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]:</span>
                <span class="n">lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="p">)</span>

        <span class="k">return</span> <span class="s">&#39;</span><span class="se">\n</span><span class="s">&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lines</span><span class="p">)</span>

</div>
<div class="viewcode-block" id="RstModuleDirectory"><a class="viewcode-back" href="../../../_generated/pyamp_documentation_rstGeneration.html#pyamp.documentation.rstGeneration.RstModuleDirectory">[docs]</a><span class="k">class</span> <span class="nc">RstModuleDirectory</span><span class="p">(</span><span class="n">RstBase</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;The RstModuleDirectory encapsulates the functionality of writing a</span>
<span class="sd">    file in reStructured text format for a given Python module which is</span>
<span class="sd">    a directory containing one or more Python sub-modules.</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">ModulePrefix</span> <span class="o">=</span> <span class="s">&quot;mod_&quot;</span>

    <span class="n">contentFunctions</span> <span class="o">=</span> <span class="p">[</span>
        <span class="s">&quot;_getTitle&quot;</span><span class="p">,</span>
        <span class="s">&quot;_getTocTree&quot;</span><span class="p">,</span>
        <span class="s">&quot;_getSubModules&quot;</span>
        <span class="p">]</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">subFiles</span><span class="p">,</span> <span class="n">subDirectories</span><span class="p">,</span> <span class="n">logData</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;</span>
<span class="sd">        * moduleName -- The name of the module which contains this module</span>
<span class="sd">        * subFiles -- The list of sub-file modules for this module</span>
<span class="sd">        * subDirectories -- The list of sub-directory module for this module</span>
<span class="sd">        *  -- The LogData object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">RstBase</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">logData</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__files</span> <span class="o">=</span> <span class="n">subFiles</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__directories</span> <span class="o">=</span> <span class="n">subDirectories</span>

    <span class="k">def</span> <span class="nf">_getFilename</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the name of the RST file to write.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="c"># Replace periods with underscores in the module name for</span>
        <span class="c"># use in the filename</span>
        <span class="n">moduleName</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">,</span> <span class="s">&quot;_&quot;</span><span class="p">)</span>

        <span class="c"># Prefix the filename to indicate that this is a module directory entry</span>
        <span class="k">return</span> <span class="s">&quot;</span><span class="si">%s%s%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">ModulePrefix</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">extension</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_getTitle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return reStructured text lines needed to create the title for this</span>
<span class="sd">        Python module</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">title</span> <span class="o">=</span> <span class="s">&quot;The </span><span class="si">%s</span><span class="s"> module&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_baseName</span>
        <span class="n">titleLine</span> <span class="o">=</span> <span class="s">&quot;=&quot;</span> <span class="o">*</span> <span class="mi">80</span>

        <span class="k">return</span> <span class="p">[</span><span class="n">titleLine</span><span class="p">,</span> <span class="n">title</span><span class="p">,</span> <span class="n">titleLine</span><span class="p">]</span>

    <span class="k">def</span> <span class="nf">_getTocTree</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the reStructured text lines needed to create the table of</span>
<span class="sd">        contents tree for this Python module.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">lines</span> <span class="o">=</span> <span class="p">[</span>
            <span class="s">&quot;.. toctree::&quot;</span><span class="p">,</span>
            <span class="s">&quot;   :maxdepth: 3&quot;</span>
            <span class="p">]</span>

        <span class="k">return</span> <span class="n">lines</span>

    <span class="k">def</span> <span class="nf">_getSubModules</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the reStructured text lines needed to create the list of</span>
<span class="sd">        sub-modules for this Python module.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">dirs</span> <span class="o">=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">__getDir</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">__directories</span><span class="p">]</span>
        <span class="n">files</span> <span class="o">=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">__getFile</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">__files</span><span class="p">]</span>

        <span class="c"># Place the directory entries before the file entries</span>
        <span class="k">return</span> <span class="n">dirs</span> <span class="o">+</span> <span class="n">files</span>

    <span class="k">def</span> <span class="nf">__getFile</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the reStructured text lines needed to create a single table</span>
<span class="sd">        of contents entry for this Python module corresponding to a single</span>
<span class="sd">        Python file.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">spacing</span> <span class="o">=</span> <span class="s">&quot; &quot;</span> <span class="o">*</span> <span class="mi">3</span>

        <span class="c"># Grab the base module name for this file</span>
        <span class="n">baseName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>

        <span class="c"># Replace periods with underscores to correlate to the actual RST</span>
        <span class="c"># file name</span>
        <span class="n">moduleName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">,</span> <span class="s">&quot;_&quot;</span><span class="p">)</span>

        <span class="c"># Add the modified directory location if this module is found</span>
        <span class="c"># in the list of modules to ignore</span>
        <span class="n">ignoredModules</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">ignoredModules</span>
        <span class="k">if</span> <span class="n">baseName</span> <span class="ow">in</span> <span class="n">ignoredModules</span> <span class="ow">or</span> <span class="n">moduleName</span> <span class="ow">in</span> <span class="n">ignoredModules</span><span class="p">:</span>
            <span class="n">moduleName</span> <span class="o">=</span> <span class="s">&quot;../</span><span class="si">%s</span><span class="s">/</span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">modifiedDirectory</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">)</span>

        <span class="c"># Add spacing to the front of the module name, </span>
        <span class="k">return</span> <span class="s">&quot;</span><span class="si">%s%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">spacing</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__getDir</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the reStructured text lines needed to create a single table</span>
<span class="sd">        of contents entry for this Python module corresponding to a directory</span>
<span class="sd">        containing one or more Python file.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">spacing</span> <span class="o">=</span> <span class="s">&quot; &quot;</span> <span class="o">*</span> <span class="mi">3</span>

        <span class="c"># Grab the base module name for this file</span>
        <span class="n">baseName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>

        <span class="c"># Replace periods with underscores to correlate to the actual RST</span>
        <span class="c"># module name</span>
        <span class="n">moduleName</span> <span class="o">=</span> <span class="n">moduleName</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">,</span> <span class="s">&quot;_&quot;</span><span class="p">)</span>

        <span class="c"># Add the modified directory location if this module is found</span>
        <span class="c"># in the list of modules to ignore</span>
        <span class="n">ignoredModules</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">ignoredModules</span>
        <span class="k">if</span> <span class="n">baseName</span> <span class="ow">in</span> <span class="n">ignoredModules</span> <span class="ow">or</span> <span class="n">moduleName</span> <span class="ow">in</span> <span class="n">ignoredModules</span><span class="p">:</span>
            <span class="n">moduleName</span> <span class="o">=</span> <span class="s">&quot;../</span><span class="si">%s</span><span class="s">/</span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">modifiedDirectory</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">)</span>

        <span class="c"># Add spacing to the front of the module name, and replace periods with</span>
        <span class="c"># underscores to correlate to the actual RST file name</span>
        <span class="k">return</span> <span class="s">&quot;</span><span class="si">%s%s%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">spacing</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">ModulePrefix</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">)</span>

</div>
<div class="viewcode-block" id="RstModule"><a class="viewcode-back" href="../../../_generated/pyamp_documentation_rstGeneration.html#pyamp.documentation.rstGeneration.RstModule">[docs]</a><span class="k">class</span> <span class="nc">RstModule</span><span class="p">(</span><span class="n">RstBase</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;The RstModule class encapsulates the functionality of writing a</span>
<span class="sd">    file in reStructured text format for a given Python module which is</span>
<span class="sd">    a single Python file.</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">contentFunctions</span> <span class="o">=</span> <span class="p">[</span>
        <span class="s">&quot;_getComment&quot;</span><span class="p">,</span>
        <span class="s">&quot;_getTitle&quot;</span><span class="p">,</span>
        <span class="s">&quot;_getAutoModule&quot;</span><span class="p">,</span>
        <span class="s">&quot;_getAutoClasses&quot;</span><span class="p">,</span>
        <span class="p">]</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">logData</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;</span>
<span class="sd">        * moduleName -- The name of the module which contains this module</span>
<span class="sd">        * logData -- The LogData object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">RstBase</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">logData</span><span class="p">)</span>

        <span class="c"># Find all of the classes contained within this module</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">__classes</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">__findClasses</span><span class="p">()</span>

    <span class="k">def</span> <span class="nf">_getFilename</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Return the name of the RST file to write.</span>

<span class="sd">        * options -- The :class:`RstOptions` object</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="c"># Convert periods to underscores in the module name for</span>
        <span class="c"># use in the filename</span>
        <span class="n">moduleName</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">,</span> <span class="s">&quot;_&quot;</span><span class="p">)</span>

        <span class="c"># Create a filename with the module name as a prefix</span>
        <span class="k">return</span> <span class="s">&quot;</span><span class="si">%s%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">moduleName</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">extension</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_getComment</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Get the reStructured text lines for the auto generated comment.</span>

<span class="sd">        * _options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">timestamp</span> <span class="o">=</span> <span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s">&quot;%B </span><span class="si">%d</span><span class="s">, %Y&quot;</span><span class="p">)</span>

        <span class="n">lines</span> <span class="o">=</span> <span class="p">[</span>
            <span class="s">&quot;.. </span><span class="si">%s</span><span class="s"> documentation file, created by&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_projectName</span><span class="p">,</span>
            <span class="s">&quot;   generateRsts for </span><span class="si">%s</span><span class="s"> on </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="p">,</span> <span class="n">timestamp</span><span class="p">),</span>
            <span class="s">&quot;   This file should not be modified.&quot;</span>
            <span class="p">]</span>

        <span class="k">return</span> <span class="n">lines</span>

    <span class="k">def</span> <span class="nf">_getTitle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Get the reStructured text lines for the title for this module.</span>

<span class="sd">        * _options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">title</span> <span class="o">=</span> <span class="s">&quot;The </span><span class="si">%s</span><span class="s"> module&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_baseName</span>
        <span class="n">titleLine</span> <span class="o">=</span> <span class="s">&quot;=&quot;</span> <span class="o">*</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">title</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span>

        <span class="k">return</span> <span class="p">[</span><span class="n">titleLine</span><span class="p">,</span> <span class="n">title</span><span class="p">,</span> <span class="n">titleLine</span><span class="p">]</span>

    <span class="k">def</span> <span class="nf">_getAutoModule</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">_options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Get the reStructured text lines for the automodule directive.</span>

<span class="sd">        * _options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="k">return</span> <span class="p">[</span><span class="s">&quot;.. automodule:: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="p">]</span>

    <span class="k">def</span> <span class="nf">_getAutoClasses</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Get the reStructured text lines for all the autoclass directives</span>
<span class="sd">        for this module.</span>

<span class="sd">        * options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">lines</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="n">index</span> <span class="o">=</span> <span class="mi">1</span>
        <span class="k">for</span> <span class="n">className</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">__classes</span><span class="p">:</span>
            <span class="n">lines</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__getAutoClass</span><span class="p">(</span><span class="n">className</span><span class="p">,</span> <span class="n">options</span><span class="p">))</span>

            <span class="c"># Add an empty line to all but the last class</span>
            <span class="k">if</span> <span class="n">index</span> <span class="o">&lt;</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__classes</span><span class="p">):</span>
                <span class="n">lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;&quot;</span><span class="p">)</span>
            <span class="n">index</span> <span class="o">+=</span> <span class="mi">1</span>

        <span class="k">return</span> <span class="n">lines</span>

    <span class="k">def</span> <span class="nf">__getAutoClass</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">className</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Get the reStructured text lines for a single autoclass directive.</span>
<span class="sd">        </span>
<span class="sd">        * className -- The name of the class</span>
<span class="sd">        * options -- The RstOptions to use</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="c"># Get the full module name of the class</span>
        <span class="n">fullClassName</span> <span class="o">=</span> <span class="s">&#39;.&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="p">,</span> <span class="n">className</span><span class="p">])</span>

        <span class="n">title</span> <span class="o">=</span> <span class="s">&quot;The </span><span class="si">%s</span><span class="s"> class&quot;</span> <span class="o">%</span> <span class="n">className</span>
        <span class="n">titleLine</span> <span class="o">=</span> <span class="s">&quot;-&quot;</span> <span class="o">*</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">title</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span>

        <span class="c"># Add the title to the lines</span>
        <span class="n">lines</span> <span class="o">=</span> <span class="p">[</span><span class="n">titleLine</span><span class="p">,</span> <span class="n">title</span><span class="p">,</span> <span class="n">titleLine</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">]</span>

        <span class="c"># Create the line to add the inheritance diagram</span>
        <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">inheritance</span><span class="p">:</span>
            <span class="n">inheritance</span> <span class="o">=</span> <span class="s">&quot;.. inheritance-diagram:: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">fullClassName</span>
            <span class="n">lines</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">inheritance</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">])</span>

        <span class="c"># Create the lines to include the class and its members</span>
        <span class="n">autoClass</span> <span class="o">=</span> <span class="s">&quot;.. autoclass:: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">fullClassName</span>
        <span class="n">members</span> <span class="o">=</span> <span class="s">&quot;    :members:&quot;</span>

        <span class="c"># Add the auto class directive</span>
        <span class="n">lines</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">autoClass</span><span class="p">,</span> <span class="n">members</span><span class="p">])</span>

        <span class="k">return</span> <span class="n">lines</span>

    <span class="k">def</span> <span class="nf">__findClasses</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Find the list of classes for this Python module&#39;&#39;&#39;</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="n">classes</span> <span class="o">=</span> <span class="n">getClasses</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="p">)</span>
        <span class="k">except</span> <span class="ne">Exception</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">&quot;Failed to locate classes for [</span><span class="si">%s</span><span class="s">]&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_moduleName</span><span class="p">)</span>
            <span class="n">classes</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="c"># Only keep classes that are actually part of the current project</span>
        <span class="n">classes</span> <span class="o">=</span> <span class="p">[</span><span class="n">t</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">classes</span><span class="o">.</span><span class="n">items</span><span class="p">()</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">__isProjectClass</span><span class="p">(</span><span class="n">t</span><span class="p">)]</span>

        <span class="k">return</span> <span class="n">classes</span>

    <span class="k">def</span> <span class="nf">__isProjectClass</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">classTuple</span><span class="p">):</span>
        <span class="sd">&#39;&#39;&#39;Determine if the given class tuple (where the first element in the</span>
<span class="sd">        tuple is the class name and the second element in the tuple is the</span>
<span class="sd">        class object) is part of the current module.</span>

<span class="sd">        * classTuple -- The class tuple</span>

<span class="sd">        &#39;&#39;&#39;</span>
        <span class="n">className</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">classTuple</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
        <span class="n">searchFor</span> <span class="o">=</span> <span class="s">&quot;</span><span class="si">%s</span><span class="s">.&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">_currentModuleName</span>

        <span class="k">return</span> <span class="n">className</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_currentModuleName</span><span class="p">)</span> <span class="ow">or</span> \
            <span class="n">searchFor</span> <span class="ow">in</span> <span class="nb">str</span><span class="p">(</span><span class="n">classTuple</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>

</div>
<span class="k">def</span> <span class="nf">locateRsts</span><span class="p">(</span><span class="n">moduleName</span><span class="p">,</span> <span class="n">directory</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;Return the list of :class:`RstModule`s contained within the given</span>
<span class="sd">    directory for the given project module name.</span>

<span class="sd">    * moduleName -- The module name for the Python project</span>
<span class="sd">    * directory -- The directory containing the Python modules</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">rsts</span> <span class="o">=</span> <span class="p">[]</span>

    <span class="c"># Grab the contents of the current directory</span>
    <span class="n">files</span><span class="p">,</span> <span class="n">subDirectories</span> <span class="o">=</span> <span class="n">getPythonContents</span><span class="p">(</span><span class="n">directory</span><span class="p">,</span> <span class="n">absPath</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

    <span class="c"># Determine if this is a proper Python module</span>
    <span class="n">initFile</span> <span class="o">=</span> <span class="s">&quot;__init__.py&quot;</span>
    <span class="n">fileBases</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">([(</span><span class="n">basename</span><span class="p">(</span><span class="n">f</span><span class="p">),</span> <span class="n">f</span><span class="p">)</span> <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">files</span><span class="p">])</span>

    <span class="c"># Only continue for valid Python module directories (i.e., those containing</span>
    <span class="c"># the __init__.py file)</span>
    <span class="k">if</span> <span class="n">initFile</span> <span class="ow">in</span> <span class="n">fileBases</span><span class="p">:</span>
        <span class="c"># Remove the init file from the list of files because we do not want</span>
        <span class="c"># to generate an RST file for this file</span>
        <span class="n">files</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">fileBases</span><span class="p">[</span><span class="n">initFile</span><span class="p">])</span>
        
        <span class="c"># Keep track of the list of sub-modules (files and directories)</span>
        <span class="c"># for the current module</span>
        <span class="n">subModuleFiles</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">subModuleDirs</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="c"># Generate RST classes for all of the files in this directory</span>
        <span class="k">for</span> <span class="n">filename</span> <span class="ow">in</span> <span class="n">files</span><span class="p">:</span>
            <span class="n">baseName</span> <span class="o">=</span> <span class="n">splitext</span><span class="p">(</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">))[</span><span class="mi">0</span><span class="p">]</span>

            <span class="c"># Ignore any files starting with an underscore</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="n">baseName</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">&quot;_&quot;</span><span class="p">):</span>
                <span class="n">fullModuleName</span> <span class="o">=</span> <span class="s">&#39;.&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">moduleName</span><span class="p">,</span> <span class="n">baseName</span><span class="p">])</span>

                <span class="c"># Only process the module once</span>
                <span class="k">if</span> <span class="n">fullModuleName</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">subModuleFiles</span><span class="p">:</span>
                    <span class="n">rsts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">RstModule</span><span class="p">(</span><span class="n">fullModuleName</span><span class="p">))</span>

                    <span class="c"># This file is a sub-module</span>
                    <span class="n">subModuleFiles</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">fullModuleName</span><span class="p">)</span>

        <span class="c"># Generate RST classes for all of the sub directories</span>
        <span class="k">for</span> <span class="n">subDirectory</span> <span class="ow">in</span> <span class="n">subDirectories</span><span class="p">:</span>
            <span class="n">newModuleName</span> <span class="o">=</span> <span class="s">&#39;.&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">moduleName</span><span class="p">,</span> <span class="n">basename</span><span class="p">(</span><span class="n">subDirectory</span><span class="p">)])</span>

            <span class="c"># Recurse to find the RST files for this sub-directory</span>
            <span class="n">subRsts</span> <span class="o">=</span> <span class="n">locateRsts</span><span class="p">(</span><span class="n">newModuleName</span><span class="p">,</span> <span class="n">subDirectory</span><span class="p">)</span>

            <span class="c"># If the directory contained modules then we should keep</span>
            <span class="c"># track of it</span>
            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">subRsts</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">newModuleName</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">subModuleDirs</span><span class="p">:</span>
                <span class="n">rsts</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">subRsts</span><span class="p">)</span>
                
                <span class="c"># This directory is a sub-module</span>
                <span class="n">subModuleDirs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">newModuleName</span><span class="p">)</span>

        <span class="c"># Add an entry for the module directory</span>
        <span class="n">rsts</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">RstModuleDirectory</span><span class="p">(</span><span class="n">moduleName</span><span class="p">,</span> <span class="n">subModuleFiles</span><span class="p">,</span>
                                       <span class="n">subModuleDirs</span><span class="p">))</span>

    <span class="k">return</span> <span class="n">rsts</span>


<span class="k">def</span> <span class="nf">writeRsts</span><span class="p">(</span><span class="n">rsts</span><span class="p">,</span> <span class="n">outputDirectory</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;Generate a single reStructured text file for all of the given</span>
<span class="sd">    :class:`.RstModule` objects. These files will be generated in the</span>
<span class="sd">    output directory. Use the given RstOptions when generating the files.</span>

<span class="sd">    * rsts -- The list of :class:`.RstModule` objects</span>
<span class="sd">    * outputDirectory -- The output directory where the files will be saved</span>
<span class="sd">    * options -- The RstOptions to use</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">generated</span> <span class="o">=</span> <span class="p">[]</span>

    <span class="k">if</span> <span class="n">exists</span><span class="p">(</span><span class="n">outputDirectory</span><span class="p">):</span>
        <span class="c"># Write all of the RST files to the output directory</span>
        <span class="k">for</span> <span class="n">rst</span> <span class="ow">in</span> <span class="n">rsts</span><span class="p">:</span>
            <span class="n">generated</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">rst</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">outputDirectory</span><span class="p">,</span> <span class="n">options</span><span class="p">))</span>
            
    <span class="k">else</span><span class="p">:</span>
        <span class="c"># @todo: use amp error</span>
        <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">&quot;Output directory [</span><span class="si">%s</span><span class="s">] does not exist!&quot;</span> <span class="o">%</span> \
                            <span class="n">outputDirectory</span><span class="p">)</span>

    <span class="c"># Return the list of files that were generated (filter out None which</span>
    <span class="c"># indicates that a file was not created)</span>
    <span class="k">return</span> <span class="p">[</span><span class="n">filename</span> <span class="k">for</span> <span class="n">filename</span> <span class="ow">in</span> <span class="n">generated</span> <span class="k">if</span> <span class="n">filename</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">]</span>


<span class="k">def</span> <span class="nf">generateAllRsts</span><span class="p">(</span><span class="n">projectName</span><span class="p">,</span> <span class="n">ignoredModules</span><span class="p">):</span>
    <span class="sd">&#39;&#39;&#39;Locate and generate reStructured text files for all of the Python</span>
<span class="sd">    modules located within the given project name and also being sure to ignore</span>
<span class="sd">    any modules that are in the list of modules to ignore.</span>

<span class="sd">    .. note:: This assumes a standard doctools Python project setup structure</span>
<span class="sd">       and that this function will be called from a script located within the</span>
<span class="sd">       &#39;doc&#39; directory.</span>

<span class="sd">    &#39;&#39;&#39;</span>
    <span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>

    <span class="c"># Create command line options which provide the ability to configure the</span>
    <span class="c"># RST creation from the command line</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;-v&quot;</span><span class="p">,</span> <span class="s">&quot;--verbose&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;verbose&quot;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;store_true&quot;</span><span class="p">,</span>
                      <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">&quot;True for verbose mode.&quot;</span><span class="p">)</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;-f&quot;</span><span class="p">,</span> <span class="s">&quot;--force&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;force&quot;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">&quot;store_true&quot;</span><span class="p">,</span>
                      <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">&quot;Overwrite existing files.&quot;</span><span class="p">)</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;--noInheritance&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;noInheritance&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
                      <span class="n">action</span><span class="o">=</span><span class="s">&quot;store_true&quot;</span><span class="p">,</span>
                      <span class="n">help</span><span class="o">=</span><span class="s">&quot;Do not include inheritance graphs for &quot;</span> \
                          <span class="s">&quot;all of the classes.&quot;</span><span class="p">)</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;--extension&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;extension&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">&#39;.rst&#39;</span><span class="p">,</span>
                      <span class="n">help</span><span class="o">=</span><span class="s">&quot;The extension used to save the RST files &quot;</span> \
                          <span class="s">&quot;default is &#39;.rst&#39;.&quot;</span><span class="p">)</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;-d&quot;</span><span class="p">,</span> <span class="s">&quot;--dest&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;destination&quot;</span><span class="p">,</span>
                      <span class="n">default</span><span class="o">=</span><span class="s">&#39;source/_generated&#39;</span><span class="p">,</span>
                      <span class="n">help</span><span class="o">=</span><span class="s">&quot;The destination directory for the generated RST &quot;</span> \
                          <span class="s">&quot;files. Default is source/_generated.&quot;</span><span class="p">)</span>
    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&quot;--modified&quot;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">&quot;modifiedDirectory&quot;</span><span class="p">,</span>
                      <span class="n">default</span><span class="o">=</span><span class="s">&#39;_modified&#39;</span><span class="p">,</span>
                      <span class="n">help</span><span class="o">=</span><span class="s">&quot;The name of the directory where modified RST &quot;</span> \
                          <span class="s">&quot;files pertaining to modules within this project &quot;</span> \
                          <span class="s">&quot;are stored. Default is source/_modified. Note: &quot;</span> \
                          <span class="s">&quot;The modified directory must be at the same level &quot;</span> \
                          <span class="s">&quot;as the generated directory!&quot;</span><span class="p">)</span>

    <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">_</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>

    <span class="c"># Pop up one directory to get the project trunk directory, and then</span>
    <span class="c"># underneath that should be a directory with the same name as the project</span>
    <span class="c"># which should contain all of the source files</span>
    <span class="n">cwd</span> <span class="o">=</span> <span class="n">abspath</span><span class="p">(</span><span class="n">curdir</span><span class="p">)</span>
    <span class="n">projectTrunkDir</span> <span class="o">=</span> <span class="n">split</span><span class="p">(</span><span class="n">cwd</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
    <span class="n">projectSourceDir</span> <span class="o">=</span> <span class="n">join</span><span class="p">(</span><span class="n">projectTrunkDir</span><span class="p">,</span> <span class="n">projectName</span><span class="p">)</span>

    <span class="c"># Create the RST options</span>
    <span class="n">rstOptions</span> <span class="o">=</span> <span class="n">RstOptions</span><span class="p">(</span><span class="n">inheritance</span><span class="o">=</span><span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">noInheritance</span><span class="p">,</span>
                            <span class="n">overwrite</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">force</span><span class="p">,</span>
                            <span class="n">extension</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">extension</span><span class="p">,</span>
                            <span class="n">ignoredModules</span><span class="o">=</span><span class="n">ignoredModules</span><span class="p">,</span>
                            <span class="n">modifiedDirectory</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">modifiedDirectory</span><span class="p">)</span>

    <span class="c"># Locate all of the RST files for the project</span>
    <span class="n">rsts</span> <span class="o">=</span> <span class="n">locateRsts</span><span class="p">(</span><span class="n">projectName</span><span class="p">,</span> <span class="n">projectSourceDir</span><span class="p">)</span>

    <span class="c"># Generate all of the reStructured text files for this project</span>
    <span class="n">generated</span> <span class="o">=</span> <span class="n">writeRsts</span><span class="p">(</span><span class="n">rsts</span><span class="p">,</span> <span class="n">options</span><span class="o">.</span><span class="n">destination</span><span class="p">,</span> <span class="n">rstOptions</span><span class="p">)</span>

    <span class="c"># Display output to the user</span>
    <span class="k">print</span> <span class="s">&quot;Generated [</span><span class="si">%d</span><span class="s">] files...&quot;</span> <span class="o">%</span> <span class="nb">len</span><span class="p">(</span><span class="n">generated</span><span class="p">)</span>

    <span class="c"># Print out all of the generated files for verbose mode</span>
    <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">verbose</span><span class="p">:</span>
        <span class="k">for</span> <span class="n">gen</span> <span class="ow">in</span> <span class="n">generated</span><span class="p">:</span>
            <span class="k">print</span> <span class="s">&quot;    &quot;</span><span class="p">,</span> <span class="n">gen</span>

    <span class="k">return</span> <span class="n">generated</span>
</pre></div>

          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li><a href="../../../index.html">pyamp v1.2 documentation</a> &raquo;</li>
          <li><a href="../../index.html" >Module code</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2012, Brett Ponsler.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
    </div>
  </body>
</html>